SharedAudioSession#

The SharedAudioSession interface provides a convenient way to manage and interact with the shared audio session in your script. The audio session acts as an intermediary between your script, the Scripting app, the operating system, and the underlying audio hardware, enabling you to configure and control audio behavior effectively.

Features#

• Retrieve and set audio session categories, modes, and options.
• Configure the preferred sample rate for audio input and output.
• Handle audio interruptions.
• Query device capabilities for supported categories and modes.
• Tailor audio behaviors for specific app use cases, such as video recording, voice chat, or background playback.

Methods and Properties#

1. Session Category and Options#

category#

Get the current audio session category.

1const category = await SharedAudioSession.category
2console.log(category) // Example: 'playback'

categoryOptions#

Retrieve the current audio session category options.

1const options = await SharedAudioSession.categoryOptions
2console.log(options) // Example: ['mixWithOthers', 'allowAirPlay']

setCategory(category: AudioSessionCategory, options: AudioSessionCategoryOptions[])#

Set the audio session category with specific options.

1await SharedAudioSession.setCategory('playback', ['mixWithOthers'])

2. Session Mode#

mode#

Retrieve the current audio session mode.

1const mode = await SharedAudioSession.mode
2console.log(mode) // Example: 'videoChat'

setMode(mode: AudioSessionMode)#

Set the audio session mode.

1await SharedAudioSession.setMode('voiceChat')

3. Sample Rate#

preferredSampleRate#

Retrieve the preferred sample rate in hertz.

1const sampleRate = await SharedAudioSession.preferredSampleRate
2console.log(sampleRate) // Example: 44100

setPreferredSampleRate(sampleRate: number)#

Set the preferred sample rate for audio input and output.

1await SharedAudioSession.setPreferredSampleRate(48000)

4. Interruption Handling#

addInterruptionListener(listener: AudioSessionInterruptionListener)#

Listen for audio interruptions.

1SharedAudioSession.addInterruptionListener((type) => {
2  if (type === 'began') {
3    console.log('Audio interruption began')
4  } else if (type === 'ended') {
5    console.log('Audio interruption ended')
6  }
7})

removeInterruptionListener(listener: AudioSessionInterruptionListener)#

Remove an interruption listener.

1SharedAudioSession.removeInterruptionListener(myListener)

5. Device Capabilities#

availableCategories#

Get the list of audio session categories available on the device.

1const categories = await SharedAudioSession.availableCategories
2console.log(categories) // Example: ['playback', 'record', 'soloAmbient']

availableModes#

Get the list of audio session modes available on the device.

1const modes = await SharedAudioSession.availableModes
2console.log(modes) // Example: ['default', 'videoChat', 'voiceChat']

6. Additional Properties#

isOtherAudioPlaying#

Check if other audio is currently playing on the device.

1const isPlaying = await SharedAudioSession.isOtherAudioPlaying
2console.log(isPlaying) // Example: true

secondaryAudioShouldBeSilencedHint#

Check if secondary audio should be silenced.

1const shouldSilence = await SharedAudioSession.secondaryAudioShouldBeSilencedHint
2console.log(shouldSilence) // Example: false

allowHapticsAndSystemSoundsDuringRecording#

Check if haptics and system sounds are allowed during recording.

1const allowHaptics = await SharedAudioSession.allowHapticsAndSystemSoundsDuringRecording
2console.log(allowHaptics) // Example: true

prefersNoInterruptionsFromSystemAlerts#

Check if the session prefers no interruptions from system alerts.

1const prefersNoInterruptions = await SharedAudioSession.prefersNoInterruptionsFromSystemAlerts
2console.log(prefersNoInterruptions) // Example: false

7. Session Activation#

setActive(active: boolean, options?: AudioSessionSetActiveOptions[])#

Activate or deactivate the shared audio session with optional options.

• active: Set to true to activate the session, false to deactivate it.
• options: An array of optional activation options, such as 'interruptSpokenAudioAndMixWithOthers'.

1await SharedAudioSession.setActive(
2  true,
3  ['notifyOthersOnDeactivation']
4)

8. System Settings#

setAllowHapticsAndSystemSoundsDuringRecording(value: boolean)#

Enable or disable haptics and system sounds during recording.

1await SharedAudioSession.setAllowHapticsAndSystemSoundsDuringRecording(true)

setPrefersNoInterruptionsFromSystemAlerts(value: boolean)#

Set the preference for no interruptions from system alerts.

1await SharedAudioSession.setPrefersNoInterruptionsFromSystemAlerts(true)

Enumerations#

AudioSessionSetActiveOptions#

Optional activation options:

• 'notifyOthersOnDeactivation': Notify other audio sessions when deactivating the shared audio session.

AudioSessionCategory#

Defines the session's audio category:

• 'ambient': Ambient audio, such as background music or ambient sounds.
• 'multiRoute': Multi-route audio, such as routing distinct streams of audio data to different output devices at the same time.
• 'playAndRecord': Play and record audio, such as voice chat or video conferencing.
• 'playback': Playback audio, such as music or sound effects.
• 'record': Recording audio, such as voice chat or video conferencing.
• 'soloAmbient': Solo ambient audio, such as background music or ambient sounds.

AudioSessionCategoryOptions#

Optional behaviors for audio categories:

• 'mixWithOthers': Mix with other audio sessions.
• 'duckOthers': Duck other audio sessions.
• 'interruptSpokenAudioAndMixWithOthers': Interrupt spoken audio and mix with others.
• 'allowBluetooth': Allow Bluetooth audio.
• 'allowBluetoothA2DP': Allow Bluetooth A2DP audio.
• 'allowAirPlay': Allow AirPlay audio.
• 'defaultToSpeaker': Default to speaker, even if headphones are connected.
• 'overrideMutedMicrophoneInterruption': Override muted microphone interruption.

AudioSessionMode#

Specifies the session's mode:

• 'default': Default mode.
• 'gameChat': Game chat mode.
• 'measurement': Measurement mode, such as audio input or output.
• 'moviePlayback': Movie playback mode, such as movie content.
• 'spokenAudio': Spoken audio mode, such as voice chat.
• 'videoChat': Video chat mode, such as video conferencing.
• 'videoRecording': Video recording mode, such as video conferencing.
• 'voicePrompt': Voice prompt mode, such as text-to-speech.

AudioSessionInterruptionType#

Specifies the type of interruption:

• 'began'
• 'ended'
• 'unknown'

This interface offers extensive control over audio session management in Scripting, making it suitable for building audio-heavy script like music players and video conferencing tools.